<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="zh" xml:lang="zh" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Guideline: 合理文档的7种规则</title>
<meta name="uma.type" content="Guideline">
<meta name="uma.name" content="how_to_documenting">
<meta name="uma.presentationName" content="合理文档的7种规则">
<meta name="element_type" content="other">
<meta name="filetype" content="description">
<meta name="role" content="">
<link rel="StyleSheet" href="./../../../css/default.css" type="text/css">
<script src="./../../../scripts/ContentPageResource.js" type="text/javascript" language="JavaScript"></script><script src="./../../../scripts/ContentPageSection.js" type="text/javascript" language="JavaScript"></script><script src="./../../../scripts/ContentPageSubSection.js" type="text/javascript" language="JavaScript"></script><script src="./../../../scripts/ContentPageToolbar.js" type="text/javascript" language="JavaScript"></script><script src="./../../../scripts/contentPage.js" type="text/javascript" language="JavaScript"></script><script type="text/javascript" language="JavaScript">
					var backPath = './../../../';
					var imgPath = './../../../images/';
					var nodeInfo=null;
					contentPage.preload(imgPath, backPath, nodeInfo,  '', false, false, false);
				</script>
</head>
<body>
<div id="breadcrumbs"></div>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top"><a name="Top"></a>
<div id="page-guid" value="_8ZA5sLn1Ed2Z1uvH8XKHyg"></div>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td class="pageTitle" nowrap="true">Guideline: 合理文档的7种规则</td><td width="100%">
<div align="right" id="contentPageToolbar"></div>
</td><td width="100%" class="expandCollapseLink" align="right"><a name="mainIndex" href="./../../../index.htm"></a><script language="JavaScript" type="text/javascript" src="./../../../scripts/treebrowser.js"></script></td>
</tr>
</table>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td class="pageTitleSeparator"><img src="./../../../images/shim.gif" alt="" title="" height="1"></td>
</tr>
</table>
<div class="overview">
<table width="97%" border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="50"><img src="./../../../images/guidance.gif" alt="" title=""></td><td>
<table class="overviewTable" border="0" cellspacing="0" cellpadding="0">
<tr>
<td valign="top">教大家怎么写好文档的指南。</td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<div class="sectionHeading">Main Description</div>
<div class="sectionContent">
<table class="sectionTable" border="0" cellspacing="0" cellpadding="0">
<tr valign="top">
<td class="sectionTableSingleCell"><ul>
    <li>
        <font size="4"><strong>规则1：从读者的角度编写文档</strong></font>
    </li>
</ul>
<p>
    <font     size="2">在软件编档领域，面向编写者编写文档时通常会采用两种形式：意识流或执行流。意识流写作风格将按思维在编写者头脑中出现的顺序捕捉思维，因而它缺乏有益于读者的组织结构。应该避免意识流写作风格，方法是确保自己了解文档的每一节将回答什么问题；也就是说，应该对自己的文档进行组织。</font>
</p>
<p>
    执行流写作风格将执行软件程序时的思维顺序捕获思维。这一风格对某些软件文档完全适用，但也不应该把它视为唯一的选择。
</p>
<ul>
    <li>
        <font size="4"><strong>规则2：避免出现不必要的重复</strong></font>
    </li>
</ul>
<p>
    如今，以不同的形式表达相同的想法通常有助于达到透彻理解的目的。但是，应该坚持的是，如果使相关信息保持分离不会对读者造成过多的麻烦，就不要或者尽量不要逐字重复信息。
</p>
<p>
    “我之所以将这封信写得比较长，仅仅是因为我没有时间把它写得更短一些。”&nbsp;
</p>
<ul>
    <li>
        <font size="4"><strong>规则3：避免歧义</strong></font>
    </li>
</ul>
<p>
    架构之所以有用，主要是因为它会压缩或限制过多的细节，虽然这些细节必须在系统投入实用前得到处理。有人可能会说，既然要压缩细节，那么，架构就应该是有歧义的了。即使架构可能会凭借一些详尽的细节或实现方案得以实现，但只要这些实现方案与架构相符，架构就是没有歧义的。
</p>
<ul>
    <li>
        <strong>视图包、精化和描述完整性</strong>
    </li>
</ul>
<p>
    大型软件系统视图可包含数百甚至数千个元素，以单一的表示展示这些元素以及它们之间的关系可能会产生大量难以理解的信息，对任何仅仅关注系统某一部分的涉众来说，这些信息会包含过多的内容。故此，本文档将采用易于理解的“块”来表示视图信息的方法。我们将这种块称为视图包。每个视图包都能展示系统的一个片断。这样，每个视图都包含一组视图包，每个视图包展示系统的一个小部分。<br />
    每个视图包都能在自己所处的视图中拥有子视图包，我们将父视图包向子视图包的过渡叫做精化。精化是通过一系列描述逐步透露信息的过程。精化分为分解精化和实现精化。分解精化能详细描述单一元素，揭示它们的内在结构，然后以递归方式精化这一内在结构中的每一个成员。实现精化是通过引入更多的新元素和新关系来表现更多的实现细节。<br />
    描述完整性是与精化相关的一种概念。描述完整性视图包能展示它们编档的视图内的所有元素和关系，在该视图中如果两个元素之间没有表现出任何关系，那么这两种元素之间，关系要么不存在，要么不允许存在。这种策略往往应用于向下游设计者或实现者传达指示和限制。非完整性视图包表示对该视图的后续精化或其他描述可以展示此处没有出现的元素之间的关系或附加元素。<br />
    描述完整性能大大简化视图包之间一致性检测，但它也会带来一些负面影响，使图和图解显得更加复杂和混乱，难以理解。和软件架构中的许多问题一样，这一问题不可避免地也需要一种权衡。&nbsp;
</p>
<ul>
    <li>
        <font size="4"><strong>规则4：使用标准结构</strong></font>
    </li>
</ul>
<p>
    应该制定一个有计划的标准结构方案，使文档遵守这一方案，并确保读者了解它，即采用组织已经规定好的模板和规则。
</p>
<ul>
    <li>
        <font size="4"><strong>规则5：记录基本原理</strong></font>
    </li>
</ul>
<p>
    <font     size="2">在为决策结果编档时，应该对放弃的方案进行记录并说明放弃的原因。否则，当这些决策需要接受详细检查或被迫更改时，你就会发现自己不得不重新访问相同的论据，并对自己为什么没有采用另一种方法感到困惑。从长远来看，对基本原理进行记录能为自己节约大量的时间。</font>
</p>
<ul>
    <li>
        <font size="4"><strong>规则6：使文档保持更新，但更新频度不要过高</strong></font>
    </li>
</ul>
<p>
    不完整或过时的文档无法反应实际情况。另一方面，在设计过程中，制定决策和重新评审决策将以极高的频度进行。为了反映那些无法持久的决策而对文档进行修改是一种不必要的举动。应该在开发计划中指定更新文档的特定要点或更新文档的过程。不应在制定设计决策之时记录每一个设计决策，而是应该使文档服从版本控制，并制定发布策略。
</p>
<ul>
    <li>
        <font size="4"><strong>规则7：针对目标的适宜性对文档进行评审</strong></font>
    </li>
</ul>
<p>
    只有预期文档用户才能告诉你文档是否包含以正确的方式展示的正确信息。应该需求他们的帮助。在发布文档前，应该让文档所面向的团体或若干团体的代表对它进行评审。<br />
    <br />
</p></td>
</tr>
</table>
</div>
<table class="copyright" border="0" cellspacing="0" cellpadding="0">
<tr>
<td class="copyright">Copyright &copy; 2008 版权所有 东软集团股份有限公司&nbsp; 联系邮箱:<a href="mailto:tcoe@neusoft.com">tcoe@neusoft.com</a></td>
</tr>
</table>
</td>
</tr>
</table>
</body>
<script type="text/javascript" language="JavaScript">
				contentPage.onload();
			</script>
</html>
